FormDialogBuilder
使用 API 自定义渲染一个表单，并以对话框的形式打开。
FormDialogBuilder
FormDialogBuilder 是通过代码创建表单对话框的 API 对象，你可以通过 FormDialogBuilder 来组织表单项和布局，并且像开发一个表单一样，基于表单的相关事件编写个性化的逻辑。
| 类型 | 名称 | 参数类型 | 返回类型 | 说明 |
|---|---|---|---|---|
| 方法 | addFieldSet(options) | AddFieldSetOptions | FieldSet | 在表单默认布局中添加一个字段集合， 一个字段集合会渲染成一个带有标题的区域。 |
| 方法 | addSubGrid(options) | AddSubGridOptions | SubGrid | 在表单默认布局中添加一个明细表。 |
| 方法 | addTabs() | void | Tabs | 添加一个页签布局容器， 可以在页签布局下添加子页签。 |
| 方法 | open(options) | OpenOptions | void | 初始化表单对话框 |
addFieldSet(options) 添加字段集合
addFieldSet 用于添加一个基于流式布局实现的字段集合组件。组件由两部分组成：标题区 和 字段内容区。
标题区会在左侧显示标题文字。
字段内容区中，字段按照从左到右、从上到下的顺序依次排列。通过 fieldsPerLine 属性可以设置每一行显示的字段个数。
单据中常见的表头字段的区块就是 FieldSet。
options 参数
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| title | string | 字段标题 | "" | |
| fieldsPerLine | number | 每行显示字段个数 | 4 |
返回值
语法
// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();
// 添加一个标题为 "基本信息" 的区域
const baseFieldSet = formDialogBuilder.addFieldSet({
title: '基本信息',
fieldsPerLine: 2
});
// 添加一个标题为"名称"的文本类型字段
baseFieldSet.addField({
id: "name",
title: "名称",
type: 'Text'
});
注意
如果不设置 title 属性或设置为空字符串 ""，那么对应渲染的字段集合区域就不会显示标题区域。
addSubGrid(options) 添加明细表
addSubGrid 用于添加一个以表格展示的明细表组件。组件由两部分构成：标题区 和 表格区。
标题区会在左侧显示标题文字。
表格区中，表头按照字段顺序从左到右依次构建。明细表中的每一行数据会作为表格中的一行记录进行展示。
单据中常见的明细表就是 SubGrid。
options 参数
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| id | string | 明细表字段名 | ☑️ | - |
| title | string | 明细表标题 | "" |
返回值
语法
// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();
// 添加一个标题为"人员明细"的明细表区域
const userGrid = formDialogBuilder.addSubGrid({
fieldName: 'users',
title: "人员明细"
});
// 在明细表中，添加一个标题为"人员"的外键字段，外键指向 User 表，并设置列宽为 200.
const user = userGrid.addField({
id: "user",
title: "人员",
type: "EntityRef",
source: 'User',
width: 200
});
// 在明细表中，添加一个标题为"天数"的数字字段，该字段会显示在"人员"右侧。
userGrid.addField({
id: "days",
title: "天数",
type: "Number"
});
注意
如果不设置 title 属性或设置为空字符串 ""，那么对应渲染的字段集合区域就不会显示标题区域。
addTabs(options) 添加页签容器
addTabs 用于添加一个页签模式的容器组件。如果我们创建的表单中，信息可以以某种明确的维度进行分组。那么我们可以使用页签布局来显示的表达这个分组，提高用户的体验。
单纯添加页签容器是无法工作的，页签容器（Tabs）需要页签（Tab）一起配合，才能完成一个完整的页签定义。
返回值
语法
// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();
// 添加一个页签分组
const tabs = formDialogBuilder.addTabs();
// 在页签分组下添加一个标题为"销售属性"的页签
const salesTab = tabs.addFieldSetTab({
title: "销售属性"
});
// 在"销售属性"页签中，添加"售价"字段
salesTab.addField({
id: "price",
title: "售价",
type: "Amount"
});
// 在 "销售属性" 右侧，添加一个标题为"库存属性"的页签，这个页签里显示一个明细表
const inventoryGrid = tabs.addSubGridTab({
title: "库存属性"
fieldName: "inventories"
});
注意
- 如果页签容器下没有通过
addTab或addSubGridTab来添加页签，那么最终这个页签容器不会进行渲染。 - 和
FieldSet不同，页签的title属性必填。
open(options) 初始化表单对话框
在完成表单数据和布局定义后，可以通过 open 打开表单对话框。这会同步创建一个全新的表单实例，该表单拥有独立的运行空间、独立的生命周期及相关表单上下文。如果要在这个表单上使用 Client API，则需要通过 options 来传递相关的表单事件监听处理函数。
options 参数
| 名称 | 类型 | 说明 |
|---|---|---|
| title | String | 对话框标题 |
| size | String | 对话框大小，可选值：small、middle、large、largest， 默认值：largest |
| value | Object | 表单初始值 |
| formOnLoad | Function | 表单初始化后触发，详细介绍 |
| fieldOnChanged | Function | 表单中任一字段值发生改变时被触发，详细介绍 |
| subGridOnChanged | Function | 明细表数据发生变化时，对明细表的 添加、复制、删除 会触发，详细介绍 |
| subGridRowOnCreated | Function | 在明细行创建之后触发，详细介绍 |
| subGridRowOnInit | Function | 在明细行初始化之后触发，详细介绍 |
| dialogOnCancel | Function | 在用户点击 对话框右上角 或 底部取消按钮 时触发，详细介绍 |
| dialogOnConfirm | Function | 在用户点击 底部确认按钮 时触发，详细介绍 |
| extraButtons | FormDialogButton[] | 额外的按钮，添加在取消和确定中间 |
FormDialogButton 类型
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| id | string | 按钮的唯一标识符 | ☑️ | - |
| text | string | 按钮显示的文本 | - | |
| title | string | 按钮的提示信息（tooltip） | - | |
| type | string | 按钮类型，可选值：flat、raised、outline、icon | - | |
| icon | string | 按钮图标 | - | |
| iconSize | number | 图标大小 | - | |
| onClick | Function | 按钮点击事件的处理函数，接收 FormExecutionCtx 作为参数 | ☑️ | - |
FieldSet 字段集合
FieldSet 是一个基于流式布局实现的字段集合，集合中的字段按照从左到右、从上到下的顺序依次排列。你可以通过 addField 给相应集合中添加字段。
| 类型 | 名称 | 参数类型 | 返回类型/类型 | 说明 |
|---|---|---|---|---|
| 方法 | addField(options) | AddFieldOptions | Field | 在字段集合中添加一个字段 |
addField(options) 添加字段
在字段集合 FieldSet 中添加一个字段。添加的多个字段会按照 addField 的调用顺序决定 FieldSet 中的展示顺序。
options 参数
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| id | string | 字段名称 | ☑️ | - |
| title | string | 字段标题 | ☑️ | - |
| type | FieldType | 字段类型 | ☑️ | - |
各类型特定参数说明
- Number
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| decimal | number | 小数位精度 | 2 |
- Percent
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| decimal | number | 小数位精度 | 2 |
- EntityRef, EnumRef
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| source | string | 指定引用对象 | ☑️ | - |
- MultiEntityRef, MultiEnumRef
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| source | string | 指定引用对象 | ☑️ | - |
- Attachment
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| disableUpload | boolean | 是否禁用上传 | false | |
| disableDelete | boolean | 是否禁用删除 | false | |
| disableEdit | boolean | 是否禁用编辑 | false | |
| enableIncremental | boolean | 是否启用增量处理 | false | |
| compact | boolean | 是否紧凑模式 | false | |
| resourceId | string | 资源ID | - | |
| attachmentProps | object | 附件组件透传的额外Props | - |
- Image
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| maxUploadCount | number | 最大上传图片数量 | - | |
| maxUploadSize | number | 最大上传图片大小(单位:MB) | - | |
| disabledSetDefault | boolean | 是否禁用设置默认展示图片功能 | false | |
| hideDefaultTag | boolean | 是否隐藏默认图片标签 | false |
语法
// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();
// 添加一个标题为 "基本信息" 的区域
const baseFieldSet = formDialogBuilder.addFieldSet({
title: '基本信息',
fieldsPerLine: 2
});
// 添加一个标题为"名称"的文本类型字段
baseFieldSet.addField({
id: "name",
title: "名称",
type: 'Text'
});
// 添加一个标题为"业务日期"的日期类型字段
baseFieldSet.addField({
id: "businessDate",
title: "业务日期",
type: "Date"
});
// 添加一个标题为"业务员"的外键类型字段，外键指向人员
const userField = baseFieldSet.addField({
id: "businessDate",
title: "业务员",
type: "EntityRef",
source: "User"
});
Field 字段
Field 是单个字段的API对象。你可以通过 Field 给字段设置相关选项及参数。
| 类型 | 名称 | 返回类型/类型 | 说明 |
|---|---|---|---|
| 属性 | id | string(read-only) | 字段名，在调用 addField 时指定。在获取表单数据时， 该字段的值会以 id 作为父对象（表单或明细表行）的 key。 |
| 属性 | type | string(read-only) | 字段类型，在调用 addField 时指定。 不同字段类型的交互组件不同。具体可以参考 FieldType 类型集合 |
FieldType 字段类型
| 类型 | 值类型 | 说明 |
|---|---|---|
| Text | String | 文本，普通单行文本组件。 |
| MultiText | String | 多行文本。 |
| Number | Number | 数字类型组件。 |
| Percent | Number | 百分比数值组件。 |
| *Amount | Number | 金额类组件。 |
| Year | Date | 日期，以 "年" 形式展示的日期组件 |
| YearMonth | Date | 日期，以 "年-月" 形式展示的日期组件 |
| Date | Date | 日期，以 "年-月-日" 形式展示的日期组件 |
| DateTime | Date | 日期 + 时间，以 "年-月-日 时:分" 形式展示的日期组件 |
| DateTimeSecond | Date | 日期 + 时间（秒），以 "年-月-日 时:分:秒" 形式展示的日期组件 |
| Time | Date | 时间（秒），以 "时:分:秒" 形式展示的日期组件 |
| Checkbox | Boolean | 布尔，以勾选框形式展示的组件 |
| *Select | Object | 下拉选择组件，选项需要通过 addSelectOption 来提供。 |
| EntityRef | Object | 档案、单据引用，以参照为展现形式的组件 |
| EnumRef | Object | 枚举引用，以枚举为展现形式的组件 |
| MultiEntityRef | Array | 多选档案、单据引用，以参照为展现形式的组件 |
| MultiEnumRef | Array | 多选枚举引用，以枚举为展现形式的组件 |
| Image | Object | 支持上传本地图片 |
Tabs 页签容器
Tabs 是页签容器的API对象。你可以通过 Tabs 添加页签Tab。Tabs的页签展示顺序保持和 addFieldSetTab 、addSubGridTab 的调用顺序一致。
| 类型 | 名称 | 参数类型 | 返回类型/类型 | 说明 |
|---|---|---|---|---|
| 方法 | addFieldSetTab(options) | AddFieldSetTabOptions | FieldSet | 添加一个字段集合的子页签 |
| 方法 | addSubGridTab(options) | AddSubGridTabOptions | SubGrid | 添加一个明细表的子页签 |
注意
如果页签容器下没有通过 addFieldSetTab 或 addSubGridTab 来添加页签，那么最终这个页签容器不会进行渲染。
addFieldSetTab(options) 添加字段集合页签
addFieldSetTab 用于在页签容器中添加一个字段集合页签。
options 参数
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| title | string | 字段标题 | ☑️ | "" |
| fieldsPerLine | number | 每行显示字段个数 | 4 |
注意
addFieldSetTab 中，title 属性必填。
返回值
语法
// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();
// 添加一个页签分组
const tabs = formDialogBuilder.addTabs();
// 在页签分组下添加一个标题为"销售属性"的页签
const salesTab = tabs.addFieldSetTab({
title: "销售属性"
});
// 在"销售属性"页签中，添加"售价"字段
salesTab.addField({
id: "price",
title: "售价",
type: "Amount"
});
addSubGridTab(options) 添加明细表页签
addSubGridTab 用于在页签容器中添加一个明细表页签。
options 参数
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| fieldName | string | 明细表字段名 | ☑️ | - |
| title | string | 明细表标题 | ☑️ | - |
注意
addSubGridTab 中，title 属性必填。
返回值
语法
// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();
// 添加一个页签分组
const tabs = formDialogBuilder.addTabs();
// 在 "销售属性" 右侧，添加一个标题为"库存属性"的页签，这个页签里显示一个明细表
const inventoryGrid = tabs.addSubGridTab({
title: "库存属性"
fieldName: "inventories"
});
// 库存属性明细表中，添加一个标题为"存货"的列
inventoryGrid.addField({
id: 'product',
title: '存货',
type: 'EntityRef',
source: 'Product'
})
SubGrid 明细表
SubGrid 是明细表的API对象。你可以通过 SubGrid 给明细表定义其数据结构和前端渲染组件。
| 类型 | 名称 | 返回类型/类型 | 说明 |
|---|---|---|---|
| 方法 | addField(options) | Field | 在明细表中添加一个字段。 |
注意
如果 SubGrid 没有通过 addField 添加过字段，那么最终该明细表不会渲染，并且在表单中，也不会创建该明细表的数据模型对象。
addField(options) 添加字段
在明细表中添加一个字段。添加的多个字段会按照 addField 的调用顺序从左到右进行排列。
options 参数
| 名称 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| id | string | 字段名称 | ☑️ | - |
| title | string | 字段标题 | ☑️ | - |
| type | FieldType | 字段类型 | ☑️ | - |
| source | string | 当 type = "EntityRef" 或 "EnumRef" 时， 通过 source 指定引用对象。 | - |
返回值
语法
// 创建 builder
const formDialogBuilder = qiqi.builder.createDialogBuilder();
// 添加一个标题为"人员明细"的明细表区域
const userGrid = formDialogBuilder.addSubGrid({
fieldName: 'users',
title: "人员明细"
});
// 在明细表中，添加一个标题为"人员"的外键字段，外键指向 User 表，并设置列宽为 200.
const user = userGrid.addField({
id: "user",
title: "人员",
type: "EntityRef",
source: "User"
width: 200
});
// 在明细表中，添加一个标题为"天数"的数字字段，该字段会显示在"人员"右侧。
userGrid.addField({
id: "days",
title: "天数",
type: "Number"
});